Taeluf.com

Code Scrawl

Documentation Generation with @‌verbs() in markdown for special functionality and templates for common documentation needs. Define your own verbs & templates.

Integrated with @easy_link(tlf, php/lexer) for ASTs of PHP classes (there may be bugs & it's tested only with php 7.4).

Run scrawl with vendor/bin/scrawl from your project root.

Example .docsrc/README.src.md

See below for a list of templates & @‌verbs available to use.

This would display the ## Install instructions and ## Configure instructions as below

# Code Scrawl
Intro text

## Install
@‌template(php/compose_install, taeluf/code-scrawl)

## Configure
Create a file `.config/scrawl.json` or `scrawl.json` in your project root. Defaults:
‌```
@‌file(code/defaults.json)
‌```

Install

@template(php/composer_install, taeluf/code-scrawl)

Configure

Create a file .config/scrawl.json or scrawl.json in your project root. Defaults:

@file(code/defaults.json)

Define your own verbs

In your scrawl-bootstrap.php file, do something like:

@file(test/input/run-cli/scrawl-bootstrap.php)

Write your own templates

Look at existing templates in @see_file(.doctemplate/) or @see_file(code/Template) for examples.

Run Scrawl

cd into your project root

# run documentation on the current dir
vendor/bin/scrawl

File Structure (defaults)

  • .config/scrawl.json: configuration file
  • .docsrc/*.src.md: documentation source files (from which your documentation is generated)
  • docs/: generated documentation output
  • code/*, and test/*: Code files to scan
  • .doctemplate/*.md.php and CodeScrawl/code/Template/*.md.php: re-usable templates
  • scrawl-bootstrap.php: Runs before $scrawl->run() and has access to $scrawl instance

@‌Verbs

Write these in your markdown source files for special functionality
@template(Scrawl/MdVerbs)

Templates

Templates can be loaded with @‌template(template_name, arg1, arg2), though ast templates should be loaded with @‌ast(class.ClassName.ast_path, ast/template_name) where the template name is optional.

Click the link to view the template file to see the documentation on how to use it & what args it requires @template(Scrawl/Templates)

Exports (from code in scan dirs)

In a docblock, write @‌export(Some.Key) to export everything above it.

In a block of code (or literally anywhere), write // @‌export_start(Some.Key) then // @‌export_end(Some.key) to export everything in between.

See @see_file(test/run/SrcCode.php) for examples

More Info

  • Run withOUT the cli: Some of the configs require absolute paths when running through php, rather than from the cli. An example is in @see_file(test/run/Integrate.php) under method testRunFull()
  • @‌literal: Displaying a literal @‌literal in an md source file can be done by putting a @hard_link(https://unicode-explorer.com/c/200C, Zero Width Non-Joiner) after the arroba (@). You can also use a backslash like so: @\literal, but then the backslash prints
  • All classes in this repo: @see_file(docs/ClassList.md)
  • $scrawl has a get/set feature. In a template, you can get an ast like $scrawl->get('ast.Fully\Qualified\ClassName'). Outside a template, you can use the Php class (@see_file(code/Ext/Php.php)) to get an ast from a file or string.
  • the deleteExistingDocs config has a bit of a sanity check to make sure you don't accidentally delete your whole system or something ...